home *** CD-ROM | disk | FTP | other *** search
/ ShareWare OnLine 2 / ShareWare OnLine Volume 2 (CMS Software)(1993).iso / util1 / exc23.zip / EXC.DOC next >
Text File  |  1993-04-13  |  64KB  |  1,460 lines

  1.                                EXC USER'S GUIDE
  2.  
  3.                      Copyright 1993 by Gary C. Crider and
  4.                                Parity Solutions
  5.                                
  6.  
  7.  
  8. TABLE OF CONTENTS:
  9.  
  10.         What is EXC? ..................................... 1.0
  11.         The EXC command line ............................. 2.0
  12.           Parameters that contain quotes ................. 2.1
  13.         Operational notes ................................ 3.0
  14.           General notes .................................. 3.1
  15.           Interrupt keys ................................. 3.2
  16.           Memory usage ................................... 3.3
  17.           Timing considerations .......................... 3.4
  18.           When EXC may not function or cause problems .... 3.5
  19.           Error handling ................................. 3.6
  20.         Scripts .......................................... 4.0
  21.           Script Commands ................................ 4.1
  22.             BEEP ......................................... 4.1.1
  23.             CASE ......................................... 4.1.2
  24.             CLEAR ........................................ 4.1.3
  25.             CURSOR ....................................... 4.1.4
  26.             DELAY ........................................ 4.1.5
  27.             GOTO ......................................... 4.1.6
  28.             HIDEWIN ...................................... 4.1.7
  29.             IFN .......................................... 4.1.8
  30.             IFY .......................................... 4.1.9
  31.             KEY .......................................... 4.1.10
  32.             LOCATE ....................................... 4.1.11
  33.             LOOK ......................................... 4.1.12
  34.             ON ........................................... 4.1.13
  35.             PAUSE ........................................ 4.1.14
  36.             QUIT ......................................... 4.1.15
  37.             READ ......................................... 4.1.16
  38.             SCRMAX ....................................... 4.1.17
  39.             SEARCH ....................................... 4.1.18
  40.             SETWAIT ...................................... 4.1.19
  41.             SHOW ......................................... 4.1.20
  42.             SHOWAT ....................................... 4.1.21
  43.             SHOWWIN ...................................... 4.1.22
  44.             TICK ......................................... 4.1.23
  45.             TIME ......................................... 4.1.24
  46.             TIMEOUT ...................................... 4.1.25
  47.             TYPE ......................................... 4.1.26
  48.             TYPFILE ...................................... 4.1.27
  49.             WAITFOR ...................................... 4.1.28
  50.             WAITSCR ...................................... 4.1.29
  51.             WINCOLS ...................................... 4.1.30
  52.             WINMAX ....................................... 4.1.31
  53.             WINROWS ...................................... 4.1.32
  54.           Labels ......................................... 4.2
  55.           Remarks ........................................ 4.3
  56.           Environment variable substitution .............. 4.4
  57.           Example script ................................. 4.5
  58.         Installation ..................................... Appendix A
  59.         Keycode table .................................... Appendix B
  60.         Disclaimer ....................................... Appendix C
  61.         Support .......................................... Appendix D
  62.         Registration ..................................... Appendix E
  63.  
  64.  
  65. 1.0 What Is EXC?
  66.  
  67.    As administrator of a large local area network, I believe whole-
  68. heartedly in automating every task that can be automated.  Even though 
  69. many tasks are computerized, that does not make them automated.  By
  70. automated I mean that you enter one command or batch file name on the
  71. DOS command line and forget about it until the task is performed.  Unfor-
  72. tunately many, if not most, programs require an operator to fill in blanks,
  73. select choices or otherwise interact with the PC to accomplish a task in
  74. which all of these parameters and choices were known to the user beforehand.
  75.  
  76.    I, for one, do not want to have to sit and watch my backups take place.
  77. In fact, I want them done while I am away from the office.  After backups, 
  78. what better time to defragment a hard disk?  Do I want to have to chase menus 
  79. to achieve this after the backup completes?  One of the worst offenders of 
  80. this I have seen is Stacker's SDEFRAG program.  You can automate just about 
  81. everything until the defrag has finished, then a stupid dialogue box pops up 
  82. and asks you if you want to exit the program.  No way to just move on back 
  83. to the batch file and begin defragmenting the next drive.
  84.  
  85.    I first experimented with various keyboard stuffers such as PC Magazine's
  86. KEY-FAKE by Charles Petzold and STACKEY by Barry Simon and Richard Wilson.
  87. These programs take pre-programmed key sequences and stuff them into the
  88. keyboard buffer as if you had typed them at the keyboard.  The trouble is
  89. that many programs rudely clear the keyboard buffer before requesting you to 
  90. enter something or they allow you to interrupt the processing by pressing any 
  91. key.  Since you have already simulated pressing the key, oops!.  In either 
  92. case, you can't simply preprogram your reply and go.  Stacker's SDEFRAG exit 
  93. prompt is an example.  
  94.  
  95.    Stuffers usually offer a way to get around this by programming a delay
  96. into the keystrokes that causes so many seconds to elapse before the key
  97. code is stuffed into the keyboard buffer.  This is a help, but what if the
  98. time for a task (backup and defrag, for example) to complete varies greatly
  99. from one execution to another?  You have to program for the longest possible 
  100. execution time and the task then takes way too long to run in most cases.
  101.  
  102.    Another problem I have with stuffers is that they are almost always 
  103. terminate-and-stay-resident (TSR) programs.  I hate to stuff another program
  104. in my 640k when I don't have to.  Although most allow you to unload them,
  105. you will forget more often than not.
  106.  
  107.    I then came across a program called AUTOMATE by Geoff Friesen that was
  108. a better approach.  You built a script, compiled it and executed it.  No
  109. TSR remained in memory.  The trouble is, the only commands in the script
  110. were execute a program, wait, and insert keys in the buffer.  Also, you
  111. couldn't pass parameters to the program.  AUTOMATE served as my inspiration 
  112. to take it further.
  113.  
  114.    What I wanted was a program that had the intelligence to monitor the 
  115. screen and detect when an event occurred that required me to insert more 
  116. keycodes in the buffer.  I would also like to see logical branching in the 
  117. script and the ability to plan for exception processing as well as when 
  118. everything performs normally.  I want to be able to enter keyboard input 
  119. when a certain string appears on the screen or when a string such as 
  120. "Please wait..." disappears from the screen.  There are times I just want 
  121. to wait until any change at all occurs on the screen.
  122.  
  123.    EXC then, is more than just a buffer stuffer.  It is a script (a.k.a. 
  124. macro) processor that has a very simple script language that allows very 
  125. complex scripts to execute much faster than you could execute them in attended 
  126. mode.  There are only slightly over thirty commands in the entire script 
  127. language!  Only about a dozen of these will be used often.  The script 
  128. language is interpretive, so no compile is needed.  It is not a TSR, so 
  129. nothing remains to eat up your precious RAM.
  130.  
  131.    EXC can even be used with your favorite DOS communications program to
  132. process online scripts.  Send CIS mail, download files, etc.
  133.  
  134.    You simply execute EXC specifying the script file to use and the program
  135. to be executed.  You include all command line parameters for the program
  136. as usual.  By combining EXC executions in batch files, extremely complex
  137. processing can be reduced to a single DOS command.  EXC even returns the
  138. same DOS ERRORLEVEL that your program returned upon completion.
  139.  
  140.    All you need to know now is the format of the EXC command line and how
  141. to write a script.
  142.  
  143.  
  144.  
  145. 2.0 The EXC Command Line
  146.  
  147.    Format: EXC [path]scriptfile [[path]program] [command-line parameters]
  148.  
  149.    The scriptfile is the filename of the script to be processed.  The 
  150. extension, if specified, must be .SCR, but is not required to be specified.
  151. the script file is assumed to be in the current directory if a path is
  152. not specified.
  153.  
  154.    The program does not require an extension, but it must be a .EXE or
  155. .COM executable program file.  .BAT files cannot be executed with EXC.  If
  156. the path is not specified, the environment PATH= directories are searched.
  157. If the program is omitted from the command line, COMMAND.COM is assumed.
  158.  
  159.    The command-line parameters are any parameters that you would specify
  160. on the DOS command line if you were executing the program external to EXC.
  161.  
  162.  
  163. 2.1 Parameters that contain quotes
  164.    
  165.    If you try to pass command-line parameters to the spawned program that 
  166. contain imbedded quotes, you must use \q in place of the quotes to be 
  167. imbedded within the parameter.
  168.  
  169.    Parameters that contain spaces, |, < or > must be enclosed in quotes in
  170. order to be treated as a single parameter.
  171.  
  172.    If you want the spawned program to receive a parameter that looks like:
  173.      Help "Me" Out,
  174.    you would include it on the EXC command line as 
  175.      "Help \qMe\q Out"
  176.  
  177.   Confusing?  You bet!  But I have to work within the rules of DOS and the
  178. parameter passing rules of different languages and compilers. Amazingly, they
  179. do not all handle quoted strings in the same manner.  I learned this the
  180. hard way by publishing a release (v2.2) that did not work when spawning most
  181. PASCAL and assembler programs.
  182.  
  183.  
  184.  
  185.  
  186. 3.0 Operational notes   
  187.  
  188. 3.1 General notes
  189.  
  190.    If you want EXC scripts to execute multiple programs and/or enter 
  191. intrinsic DOS commands on the DOS command line, omit the program from
  192. the EXC command line or specify COMMAND.COM which is the default.  Your
  193. script will begin executing on an empty DOS command line.  When using
  194. COMMAND.COM as the object of an EXC script, you must terminate the script
  195. with:
  196.  
  197.   QUIT
  198.   -or-
  199.   TYPE "EXIT"
  200.   KEY <ENTER>
  201.  
  202. in order to terminate the second copy of COMMAND.COM that you have loaded
  203. and allow EXC to complete.  If you don't, you could end up eating up your
  204. conventional memory with copies of EXC and COMMAND.COM.  QUIT automatically
  205. issues the EXIT if COMMAND.COM was invoked.  The same occurs when EXC
  206. encounters end-of-file on your script file.  If you terminate the script
  207. with LEFT SHIFT-RIGHT SHIFT, you need to type EXIT at the DOS prompt to
  208. terminate the COMMAND.COM that you started and remove EXC from memory.
  209.    
  210.    Don't get cute and try to execute EXC as the object program of an EXC
  211. command.  While it might logically work, I can see no possible need for
  212. such action and you and your system are at your own risk.
  213.  
  214.    EXC creates an extended keyboard buffer that will hold 256 keycodes.  The
  215. DOS keyboard buffer will hold 16 keycodes.  Thus you may stuff up to 528
  216. keycodes with TYPE and KEY before the program requests keyboard input.  If
  217. you overflow this buffer (very unlikely), a runtime error occurs and script
  218. processing is halted.
  219.  
  220.    EXC is written in Borland C++, a product of Borland International.
  221.  
  222.  
  223. 3.2 Interrupt keys
  224.  
  225.    You can pause execution of a script by pressing the Scroll Lock key.  If   
  226. your keyboard has a Scroll Lock indicator light, the light will be on while   
  227. the script is paused.  Pressing Scroll Lock again resumes execution of the
  228. script exactly where it left off.  Any unexpired wait time must elapse
  229. before another command is processed.
  230.  
  231.    You can terminate execution of a script by holding down both the LEFT
  232. and RIGHT SHIFT keys.  A beep will indicate that the script is being
  233. terminated.  Execution of any spawned program will continue.
  234.  
  235.    The Pause key on your keyboard pauses all execution at the time the next
  236. screen write occurs.  Timer interrupts continue.  EXC detects the pause
  237. state and suspends itself.  When you strike any key, both EXC and the
  238. spawned task will resume processing.  Any unexpired wait time must elapse
  239. before another command is processed.  While paused, the spawned program
  240. remains active.
  241.    
  242.    Since EXC is executing as a timer interrupt with your program operating
  243. as a spawned subtask, cycle-stealing multitasking is occurring.  This can 
  244. cause a few problems.  If you must interrupt execution of your program, your 
  245. best bet may actually be pressing CTRL-ALT-DEL to reboot the computer.  If 
  246. you hit CTRL-BREAK, you will normally interrupt just one task while the other
  247. continues.  Pressing CTRL-BREAK again then interrupts the remaining task.
  248. This can confuse the remaining task to no end and lead to a system lock-up
  249. or other undesirable result.  If you are lucky, you may actually get by with 
  250. it, but I don't recommend it.  Even if you terminate EXC with LEFT SHIFT-
  251. RIGHT SHIFT, the timer interrupt is still active until your program 
  252. terminates, so the same problem can occur.
  253.  
  254.  
  255. 3.3 Memory usage
  256.  
  257.    EXC requires approximately 40K of conventional memory overhead.  After
  258. loading, it then allocates a buffer to hold your script file and a buffer
  259. for reading the screen contents.  If your application program's requirements 
  260. are pushing the limits of available RAM, you may not be able to execute it 
  261. under EXC control.  If COMMAND.COM is spawned, an additional 3K (DOS 5) is 
  262. used.
  263.  
  264.    The screen buffer varies according to the screen size active at startup or
  265. the value specified in a SCRMAX command.  It will require one byte for every
  266. character position on the screen, plus 4 bytes.  Thus an 80 x 25 text mode 
  267. will require a buffer of 2004 bytes.  If SCRMAX is present, that buffer size
  268. is always allocated, regardless of the initial text mode.
  269.  
  270.    The script buffer is the size required to hold all script commands strung
  271. end-to-end with 1 byte between each command.  Leading and trailing spaces
  272. are not counted.  If you use TYPFILE, the contents of the specified file are
  273. added to the script buffer.  Thus, your script buffer will increase by the 
  274. size of all files specified in TYPFILE commands.  If you specify the same
  275. file in two different TYPFILE commands, the file will be loaded into memory 
  276. twice.  If the TYPFILE is executed multiple times within a loop, it only 
  277. requires buffer space for a single copy of the file.
  278.  
  279.    With 604k of available memory, I am able to load a simple script with
  280. 35,000 fairly short commands.  
  281.  
  282.    Versions prior to 2.0 were limited to a total memory allocation of 64k 
  283. for all buffers.
  284.  
  285.    If your script is too large, you may encounter an error allocating script
  286. memory, allocating screen buffer memory or you will encounter an error that
  287. says you do not have enough memory to spawn your program.
  288.    
  289.  
  290. 3.4 Timing considerations
  291.  
  292.    EXC installs itself as a timer interrupt that is invoked 18.2 times
  293. per second.  If it has no work to do, it simply executes the system timer
  294. interrupt and any other chained timer interrupts and returns.  During waits 
  295. (DELAY, WAITFOR, etc.) the frequency of invocation is reduced to twice per 
  296. second.  This minimizes the impact of the interrupt on the performance of 
  297. your program.  A half-second is forever to most computers.  This also means
  298. that if you are searching for a string with WAITFOR, and the string flashes 
  299. on the screen for less than 1/2 second, it will not be detected.
  300.  
  301.    Needless to say, EXC does not have but 1/18th of a second to retrieve and
  302. execute a command.  This is a long time in a fast computer and a short
  303. time to a slow system.  I try to break commands down into logical parts that
  304. are executed in consecutive interrupts.  Obviously, there are some commands
  305. that will probably take longer than 1/18th of a second, especially on slower
  306. systems.  EXC is a handler for interrupt 1C.  No new 1C interrupts are
  307. initiated by the system until the active one is complete.  While missing
  308. a few interrupts does not hurt EXC or DOS, it could effect a spawned task
  309. or TSR that is also servicing 1C interrupts.
  310.  
  311.  
  312. 3.5 When EXC may not function or cause problems
  313.  
  314.    GRAPHICS MODES do not store text characters in video memory, only pixels
  315. of differing colors.  EXC cannot interpret these pixels into characters, thus
  316. commands that are based on screen reads will not work in graphics modes.
  317.  
  318.    In order to execute screen reads an writes rapidly due to timing 
  319. restraints, EXC reads and writes (SHOW, SHOWIN, READ, WAITFOR, WAITSCR, etc.)
  320. directly to and from video memory at pages B000-B7FF.  If you use DESQVIEW
  321. or a special graphics mode that relocates the active video page outside
  322. this area, screen reads and writes will not function properly.  This also
  323. prevents these commands from working properly in CGA modes.  All VGA text
  324. modes and most SVGA text modes should work properly.  If you use programs
  325. that change to a different text resolution during processing, please be sure 
  326. to read about the SCRMAX command.
  327.  
  328.    If the program you are executing or a TSR that is loaded in memory moves
  329. or otherwise messes with the DOS keyboard buffer, it could cause EXC to
  330. malfunction.  The most likely symptom would be keys that you TYPE or KEY
  331. not showing up or not appearing to have been pressed.  EXC uses BIOS 
  332. interrupt 16h, service 5 to insert the keys into the keyboard buffer.  It
  333. does not reallocate or move the buffer.  It merely creates a new extended
  334. buffer that only EXC is aware of.  As the timer interrupts occur, EXC
  335. always checks to see if anything is in the extended buffer, if so it will
  336. move as many keycodes as the PC keyboard buffer will hold into the keyboard
  337. buffer, or until the extended buffer is empty.  BIOS interrupt 16h is not
  338. available until later XT BIOSes.  As a general rule, EXC should not be used
  339. except on AT models or later.
  340.  
  341.    Other factors that could cause EXC to malfunction include programs and
  342. TSRs that have timer and keyboard interrupt handlers.  Customary usage of
  343. these interrupts provides for allowing other installed handlers to perform
  344. their function, but you cannot count on all programmers to abide by these
  345. conventions.
  346.  
  347.    If a TSR or spawned task is using timer interrupt 1C for timing (music,
  348. communications, etc.) the timing could be thrown off slightly by EXC, 
  349. especially in slower systems.  In most cases, the effect will be negligible.
  350.  
  351.    DOS 5.0's EDIT program, in the pull-down menus, accepts keyboard input 
  352. from the keyboard buffer, but will not process that key press until it 
  353. receives an interrupt from the keyboard.  EXC cannot simulate hardware 
  354. interrupts.  This is the only program I have seen that does this, but since 
  355. EDIT is the editor used by QuickBASIC I suppose it will also have the same 
  356. problem.  Other Microsoft products may also use this technique.
  357.  
  358.    If you spot another program, video mode or anything else that causes
  359. EXC to malfunction, send me a CIS mail or U.S. mail note and I will check
  360. it out if I can.  I will include a note in this section on those reported
  361. problems.
  362.  
  363.  
  364. 3.6 Error handling
  365.  
  366.    If an error occurs that prevents EXC from initiating the program, a
  367. message will appear and a DOS ERRORLEVEL of 255 will be returned.  If
  368. the program is successfully initiated, EXC will return the DOS ERRORLEVEL
  369. that the program returned when it completed.  There is an RC = nnn message
  370. after EXC terminates that displays the DOS ERRORLEVEL returned by your
  371. program and by EXC.  When COMMAND.COM is executed, the ERRORLEVEL will
  372. not reflect what was returned from one of the programs you executed and
  373. will always be zero.
  374.  
  375.    If EXC encounters an error while processing the script (i.e. an invalid
  376. script statement) it will sound two short beeps on the PC speaker and
  377. terminate processing any more script commands.  When the spawned program
  378. completes or is exited, a message will appear specifying the error EXC 
  379. encountered.
  380.  
  381.    If the spawned program terminates before EXC has finished processing
  382. the script, all script processing terminates at that point.  Keycodes
  383. that have been stuffed into the buffer remain there.  This allows you
  384. to enter a new command on the DOS command line from within your script.
  385. You can actually chain EXC processing without the use of a batch file.
  386.  
  387.  
  388. 4.0 Scripts
  389.  
  390.   Scripts can be written with any ASCII text file editor.  There is one 
  391. command per line.  Leading and trailing blanks and tabs, lines beginning with 
  392. a semicolon (;) and blank lines are ignored by the script processor.  You may 
  393. have more than one blank between the command and its parameter(s).
  394.  
  395.   All window coordinates specified in some commands are based on the full 
  396. screen currently displayed.  The upper right corner is column 1, row 1.
  397.  
  398.   All "string" parameters can accept quotes within the string by placing
  399. the characters \q (lower case) in the string where you want a quote to
  400. occur.
  401.  
  402.  
  403. 4.1 Script Commands
  404.  
  405.  Note: Brackets ([]) indicate an optional parameter and should not be
  406.        included as part of the command.  Quotes (""), where specified, 
  407.        are required to be entered as part of the parameter.
  408.  
  409.  BEEP                   Sound a short beep on speaker. Useful in debugging
  410.                         scripts.
  411.  CASE ON                The CASE commands enable case-sensitive (ON) or case-
  412.  CASE OFF               insensitive (OFF) compares by WAITFOR and SEARCH.  The
  413.                         initial mode is CASE ON.
  414.  CLEAR                  Clear the screen.
  415.  CURSOR col row         Move the cursor to the specified coordinates.
  416.  DELAY n                Wait n seconds
  417.  GOTO label             Unconditional branch to label.
  418.  IFN label              If condition set to N, go to label.
  419.  IFY label              If condition set to Y, go to label.
  420.  HIDEWIN                Restore a window displayed with SHOWIN to it's 
  421.                         original color attributes.
  422.  KEY mnemonic [n]       Push the key onto the keyboard stack. 'n' is the
  423.                         number of times you want the keycode inserted.
  424.  LOCATE "string"        Reads the screen until the string appears, then moves 
  425.                         the cursor to the start of the string.
  426.  LOOK "string"          Test to see if the string was on the screen at the 
  427.                         time the screen was last read.  Screen reads occur
  428.                         during execution of READ, SEARCH, WAITSCR and WAITFOR 
  429.                         commands.  Sets "Y/N" condition.
  430.  ON n label             Command will do nothing n times and on pass n+1, it
  431.                         will branch to label.
  432.  PAUSE                  Causes the script to be paused as if Scroll Lock were
  433.                         pressed.
  434.  QUIT                   Halt processing the script file.
  435.                         End-of-file on the script file issues an automatic
  436.                         QUIT.
  437.  READ                   Read the current screen contents.
  438.  SCRMAX cols rows       Specifies the largest screen size that will be used       
  439.                         during execution.  Used to allocate screen buffer.
  440.  SEARCH "string"        Read screen and test to see if the string is on the 
  441.                         screen. Sets "Y/N" condition.
  442.  SETWAIT nnn            Wait nnn seconds before a WAITFOR or WAITSCR times
  443.                         out.
  444.  SHOW attr "string"     Display the string using the specified attribute.
  445.                         Displays at the location specified in SHOWAT.
  446.  SHOWAT col row         Specifies location for subsequent SHOW command
  447.                         strings to be displayed.
  448.  SHOWIN attr            Rewrite the current window text in the specified
  449.                         attribute.
  450.  TICK n                 Same as DELAY except n represents 1/18th of a second
  451.                         instead of a second.
  452.  TIME hhmmss            Pause execution of subsequent commands until the               
  453.    
  454.                         specified time of day.
  455.  TIMEOUT label          Branch to label when the next WAITFOR or WAITSCR
  456.                         timeout occurs.
  457.  TYPE "string"          Type the ASCII string.
  458.  TYPFILE filespec [mnemonic]      
  459.                         Type the contents of the specified file.  Replace
  460.                         CR/LFs with specified mnemonic.
  461.  WAITFOR [NOT] "string" Wait until the string appears on the screen.  If NOT
  462.                         specified, wait until string is not on screen.
  463.  WAITSCR                Wait until anything changes on the screen.
  464.  WINCOLS start end      Limit screen reads and SHOWIN to the screen columns
  465.                         specified.
  466.  WINMAX                 Remove row and column restraints imposed by WINCOLS
  467.                         and WINROWS.  Subsequent reads read the full screen.
  468.  WINROWS start end      Limit screen reads and SHOWIN to the screen rows
  469.                         specified.
  470.  :label                 Define a label.
  471.  
  472.  
  473. 4.1.1 BEEP
  474.  
  475.  Sounds a short BEEP on the PC speaker.  Since there is no visual feedback
  476.  for many of the operations and branches performed while processing a script,
  477.  debugging a script can be tough if it is complex.  Inserting a BEEP at a
  478.  strategic location in the script will tell you if processing ever reached
  479.  that point in the script.
  480.  
  481.  NOTE: BEEP does not extend the duration of the timer interrupt.  It actually
  482.  is turned on, then turned off a few ticks later.
  483.  
  484.  
  485. 4.1.2 CASE ON / CASE OFF
  486.  
  487.  The CASE commands determine case sensitivity during SEARCH, LOOK and WAITFOR
  488.  string searches.  If CASE is ON, the search string and screen contents are 
  489.  unchanged during the search, and must match in upper and lower case.  If 
  490.  CASE is OFF, the search string and all characters read from the screen are 
  491.  converted to upper-case before the search begins so that case does not 
  492.  influence the result of the compare.
  493.  
  494.  The initial CASE mode is ON.
  495.  
  496.  NOTE - You must reread the screen after changing the CASE mode before the
  497.  new CASE mode will take effect.
  498.  
  499.  See TIMEOUT for example.
  500.  
  501.  
  502. 4.1.3 CLEAR
  503.  
  504.  The CLEAR command clears the entire screen, not just the active window. 
  505.  It also homes the cursor.  Use with caution, this could cause problems 
  506.  within many applications.
  507.  
  508.  
  509. 4.1.4 CURSOR col row
  510.  
  511.  The cursor is moved to the location on the screen (not just within the
  512.  active window) specified by col and row.  Col and row are the screen column
  513.  and row.
  514.  
  515.  CURSOR is designed primarily to be used in a full screen editor or similar
  516.  applications where the cursor can be moved with the arrow keys.  The 
  517.  destination must be in an area of the screen where the active application 
  518.  allows typing.
  519.  
  520.  In order for your application to recognize that the cursor has been moved,
  521.  a series of <LEFT> <RIGHT> <UP> and <DOWN> keys are stuffed into the
  522.  buffer and executed until the cursor is at the desired location.  If you
  523.  send the cursor to a location that is not in an acceptable input area of
  524.  the active application, the cursor will jump around the destination, but
  525.  never get there.  You will have to terminate the script with LEFT SHIFT-
  526.  RIGHT SHIFT.
  527.  
  528.  Example:
  529.  
  530.    CURSOR 17 41
  531.  
  532.  
  533. 4.1.5 DELAY n
  534.  
  535.  Pauses execution of subsequent script commands until the specified number
  536.  of seconds has elapsed.
  537.  
  538.  Example: DELAY 3
  539.  
  540.  
  541. 4.1.6 GOTO label
  542.  
  543.  Executes an unconditional branch to the command following the specified 
  544.  label. 
  545.  
  546.  See ON for example.
  547.  
  548.  
  549. 4.1.7 HIDEWIN
  550.  
  551.  Restore the active window to its original attributes after a SHOWIN command 
  552.  has be executed.  If no SHOWIN has been executed, the results will not be
  553.  pleasing to the eye.  Also, screen reading commands must not be executed
  554.  between a SHOWIN and its corresponding HIDEWIN.  See SHOWIN for reasons for
  555.  using SHOWIN and HIDEWIN.
  556.  
  557.  See SHOWIN for example.
  558.  
  559.  
  560. 4.1.8 IFN label
  561.  
  562.  This tests the results of a previous SEARCH or LOOK command.  If the search 
  563.  string was not located on the screen, processing resumes at the command 
  564.  following the specified label.  If the string was found on the screen, 
  565.  processing resumes with the next command after the IFY command.
  566.  
  567.  If no previous SEARCH or LOOK has been issued, processing continues after 
  568.  branching to the specified label.  Thus, without a preceding SEARCH or
  569.  LOOK command, the IFN command becomes an unconditional branch equivalent to 
  570.  a GOTO command.
  571.  
  572.  The IFN statement does not have to be the next command after the SEARCH or
  573.  LOOK.
  574.  
  575.  Example:
  576.  
  577.  :Loop
  578.    READ
  579.    LOOK "XYZ"
  580.    IFN LoopEnd
  581.    .
  582.    .
  583.    .
  584.    GOTO Loop
  585.  :LoopEnd
  586.    .
  587.    .
  588.    .
  589.  
  590.  
  591. 4.1.9 IFY label
  592.  
  593.  This tests the results of a previous SEARCH or LOOK command.  If the search 
  594.  string was located on the screen, processing resumes at the command 
  595.  following the specified label.  If the string was not found on the screen, 
  596.  processing resumes with the next command after the IFY command.
  597.  
  598.  If no previous SEARCH or LOOK has been issued, the result is negative and 
  599.  processing continues without branching.  Thus, without a preceding SEARCH 
  600.  or LOOK command, the IFY statement appears as a null or nonexistent command.
  601.  
  602.  The IFY statement does not have to be the next command after the SEARCH or 
  603.  LOOK.
  604.  
  605.  See ON for example.
  606.  
  607.  
  608. 4.1.10 KEY <mnemonic> [n]
  609.  
  610.  KEY is used to enter special keys that require mnemonics (special names
  611.  enclosed in <> that represent their function) in order to input them to
  612.  the keyboard buffer.
  613.  
  614.  If n is specified, it is the number of times <mnemonic> will be inserted 
  615.  into the keyboard buffer.  For instance, if you wanted three TABs, you would
  616.  type "KEY <TAB> 3".  If n is not specified, it is assumed to be 1.
  617.  
  618.  The following key mnemonics are recognized:
  619.  
  620.  Single keys mnemonics:
  621.  
  622.  <BKSP>          <DEL>            <DOWN>           <END>            <ENTER>
  623.  <F1>-<F12>      <ESC>            <HOME>           <INS>            <LEFT>
  624.  <PGDN>          <PGUP>           <PRTSC>          <RIGHT>          <TAB>
  625.  <UP>            <GRAY5>          <GRAY+>          <GRAY->          <GRAY*>
  626.  <x>             <SPACE>
  627.  
  628.  Two key mnemonics:
  629.  
  630.  Shift key combinations: <SHF+s> or <SHF+x>     
  631.  CTL key combinations:   <CTL+s> or <CTL+x>
  632.  ALT key combinations:   <ALT+s> or <ALT+x>
  633.  
  634.  x = any ASCII value that can be entered from the keyboard with a single
  635.      key, or SHIFT + a single key.
  636.  
  637.  s = any of the single key mnemonic keywords or character except <PRTSC>.
  638.  
  639.  NOTE: Some SHF, CTL and ALT key combinations are undefined.  See the
  640.        keycode table in Appendix A.  There are no mnemonics for entering 
  641.        3-or-more-key combinations.  To detect these, a program must 
  642.        interrogate the keyboard flags to see if CTL, ALT or SHIFT are being 
  643.        held down.  This can only be done in real time as the keys are being 
  644.        pressed, therefore they cannot be simulated by placing these non-
  645.        existent key codes into the keyboard buffer.
  646.  
  647.  Examples:
  648.  
  649.    KEY <ESC> 3
  650.    KEY <CTL+F10>
  651.    KEY <ENTER>
  652.  
  653.  
  654. 4.1.11 LOCATE "string"
  655.  
  656.  The LOCATE command is mostly a combination of WAITFOR and CURSOR.  You
  657.  provide a string.  Processing will be suspended until that string appears
  658.  in the active window or a timeout occurs.  Once the string is located,
  659.  the cursor is moved, via a sequence of arrow keys stuffed in the keyboard
  660.  buffer, to the location of the first character of the string.
  661.  
  662.  LOCATE is designed primarily to be used in a full screen editor or similar
  663.  application where the cursor can be moved with the arrow keys.  The located
  664.  string must be in an area of the screen where the active application allows
  665.  typing.
  666.  
  667.  
  668. 4.1.12 LOOK "string"
  669.  
  670.  Look at the last screen that was read to see if it contains the value in
  671.  "string".  The entire active window contents will be searched to see if 
  672.  "string" was being displayed when the last screen read occurred.   The 
  673.  string may be any valid screen characters.  There is no wait involved as 
  674.  with WAITFOR.
  675.  
  676.  The screen contents are read each time a READ, SEARCH, WAITSCR, WAITFOR or
  677.  LOCATE command is executed.  In the case of WAITFOR and WAITSCR, multiple 
  678.  reads occur until a search string or change is detected.  The contents of 
  679.  the screen buffer remain as they were when the last read was executed at the
  680.  time the search string or change was detected or a timeout occurred.
  681.  
  682.  Once it has been determined whether or not "string" was being displayed,
  683.  an internal variable is set to "Y" or "N".  IFY and IFN can then be used to
  684.  test the result of the search and then branch accordingly.
  685.  
  686.  
  687. 4.1.13 ON n label
  688.  
  689.  For the first n executions of the ON command, execution simply passes to the 
  690.  next command.  On the next pass through the ON command, a branch occurs to
  691.  label.  Example:
  692.  
  693.      :LOOP
  694.        ON 5 ENDLOOP
  695.        SEARCH "ERROR:"
  696.        IFY EXIT
  697.        TYPE "xyz"      - These two instructions are executed five
  698.        KEY <DOWN>      - times unless an error message pops up.
  699.        GOTO LOOP       
  700.      :ENDLOOP
  701.        KEY <ENTER>
  702.      :EXIT
  703.        QUIT
  704.        
  705.  
  706. 4.1.14 PAUSE
  707.  
  708.  PAUSE simulates pressing the Scroll Lock key to pause the script execution.
  709.  See the section on interrupt keys for a description of pause processing.
  710.  
  711.  
  712. 4.1.15 QUIT [n]
  713.  
  714.  QUIT stops processing a script at the point where it is encountered during
  715.  script execution.  The same result is obtained when there are no more script
  716.  commands to process.
  717.  
  718.  Normally on exit, EXC returns the return code of the executed program.  If
  719.  a number (0-255) is specified with the QUIT command, that value is returned
  720.  as the DOS ERRORLEVEL return code instead of what was passed from the
  721.  spawned program.
  722.  
  723.  An example of why you would want to set a return code:
  724.  
  725.    I use EXC to control PROCOMM PLUS to execute a script that synchro-
  726.    nizes my clock with the Naval Observatory.  I need to know if it
  727.    fails.
  728.  
  729.    I can detect the error with my EXC script, but when I exit PCPLUS,
  730.    PCPLUS always returns a return code of 255.  Using the QUIT nn format,
  731.    I can set a return code of 1 on error and 0 when there is no error.
  732.  
  733.  If COMMAND.COM was invoked by the EXC command line, QUIT types EXIT and keys
  734.  <ENTER> in order for EXC to be able to complete.  If you issue the QUIT 
  735.  while another program is active, you will not obtain the desired results.
  736.  
  737.  See TIMEOUT for example.
  738.  
  739.  
  740. 4.1.16 READ
  741.  
  742.  Reads the active window for subsequent testing with the LOOK command.  Using 
  743.  a READ followed by several LOOKs that examine the same screen contents can
  744.  be much more efficient than issuing several SEARCHes, each of which reads
  745.  the entire screen contents.
  746.  
  747.  
  748. 4.1.17 SCRMAX cols rows
  749.  
  750.  I hate including technical parameters in my commands, but this one is a
  751.  must for successful operation of EXC in larger screen modes.
  752.  
  753.  Specify SCRMAX if you expect a spawned application to change to a text 
  754.  screen mode larger than the text mode in use when EXC is initiated.  For
  755.  instance, if you are in DOS with 25 rows of 80 column text and you initiate
  756.  an editor with EXC and the editor places the screen in 80x50 text mode,
  757.  specify "SCRMAX 80 50" in your script (no quotes).  Since this command is
  758.  processed when the script is being loaded into memory and not after the
  759.  script processing begins, it may be placed anywhere within your script.
  760.  Logically, it should occur at the start.  If multiple SCRMAX commands are
  761.  encountered, only the last one input will be used.  If your application will
  762.  use multiple screen sizes, specify the largest (in area: cols times rows)
  763.  that will be used.
  764.  
  765.  If you do not include SCRMAX in your script, it is assumed that the screen
  766.  size in effect when EXC is loaded and before the spawned program is loaded 
  767.  will be the maximum size needed.
  768.  
  769.  The range of text mode screen sizes supported by EXC includes from 40x20 to 
  770.  200x100 characters.
  771.  
  772.  SCRMAX can have a major impact in the amount of memory occupied by EXC.
  773.  It would seem that the logical thing for EXC to do would be to examine
  774.  the screen size before each read and allocate the screen memory buffer
  775.  accordingly at that time.  However, since EXC spawns another program which
  776.  can, and often does, allocate all of the remaining memory, EXC must pre-
  777.  allocate the largest buffer that will be required before spawning the 
  778.  program.  A screen buffer requires the same number of bytes as the rows 
  779.  times the columns, plus 4 bytes.  Thus, an 80x25 VGA text screen will 
  780.  require a 2,004 byte buffer.  I actually had a user contact me who uses a 
  781.  132x66 display (great eyes or a huge monitor!).  This would require 132 * 66 
  782.  or 8,712 bytes of memory.  
  783.  
  784.  If you do not specify SCRMAX and your program bumps up the screen size,
  785.  the effective area of the larger screen is the upper left quadrant
  786.  corresponding to the size of the screen when EXC was loaded.  This is
  787.  also true if you specify an SCRMAX smaller than the largest screen.  In
  788.  other words, if you specify SCRMAX 80 25 and your program changes to a
  789.  132x44 screen,  Only the first 80 columns and 25 rows are read by EXC's
  790.  READ, WAITFOR, WAITSCR, LOCATE and SEARCH commands.  If all of the strings
  791.  you search for and changes you wish to detect are in the upper left of
  792.  the screen, you can save memory by specifying a smaller SCRMAX size.  You 
  793.  would really have to be in a memory crunch to bother with this approach, 
  794.  I suspect.
  795.   
  796.  Examples:
  797.  
  798.    SCRMAX 80 50
  799.    SCRMAX 132 25
  800.  
  801.  
  802. 4.1.18 SEARCH "string"
  803.  
  804.  At any point in processing the script, you may check to see if certain
  805.  information is on the screen.  The entire active window will be read and 
  806.  searched to see if "string" is being displayed.   The string may be any 
  807.  valid screen characters.  There is no wait involved as with WAITFOR.
  808.  
  809.  Once it has been determined whether or not the string is being displayed,
  810.  an internal variable is set to "Y" or "N".  IFY and IFN can then be used to
  811.  test the result of the search and then branch accordingly.
  812.  
  813.  SEARCH is basically a READ followed immediately by a LOOK.
  814.  
  815.  See ON for example.
  816.  
  817.  
  818. 4.1.19 SETWAIT seconds
  819.  
  820.  This sets the timeout limit for WAITSCR, WAITFOR and LOCATE commands.  If 
  821.  processing is waiting after invoking any of these commands and the specified 
  822.  number of seconds elapses, TIMEOUT processing, described under TIMEOUT, will 
  823.  be invoked.
  824.  
  825.  You may change the SETWAIT timeout limit at any point while processing the 
  826.  script.
  827.  
  828.  If SETWAIT is set to zero, no timeout ever takes place and EXC will wait
  829.  indefinitely during WAITFOR, WAITSCR and LOCATE.  The initial value of the 
  830.  SETWAIT timer is zero. 
  831.  
  832.  See TIMEOUT for example.
  833.  
  834.  
  835. 4.1.20 SHOW attr "string"
  836.  
  837.   SHOW displays a string at a given location on the screen.  This command
  838.  is mostly useful for debugging scripts by displaying information about the
  839.  progress of the script during execution.  While mostly harmless, it can cause
  840.  problems if a spawned program reads screen memory.  Use it cautiously.
  841.   
  842.  The string is displayed at the location specified in the last executed
  843.  SHOWAT command.
  844.   
  845.  The screen attribute is the sum of a background value plus a foreground
  846.  value from the table below.  Add 128 if you want it to blink.
  847.  
  848.   Background colors:       Foreground colors:
  849.  
  850.     0 Black                 0 Black
  851.    16 Blue                  1 Blue
  852.    32 Green                 2 Green
  853.    48 Cyan                  3 Cyan
  854.    64 Red                   4 Red
  855.    80 Magenta               5 Magenta
  856.    96 Brown                 6 Brown
  857.   112 Light Gray            7 Light Gray
  858.                             8 Dark Gray
  859.                             9 Light Blue
  860.                            10 Light Green
  861.                            11 Light Cyan
  862.                            12 Light Red
  863.                            13 Light Magenta
  864.                            14 Yellow
  865.                            15 White
  866.  
  867.  See TIMEOUT for example. 
  868.  
  869.  
  870. 4.1.21 SHOWAT col row
  871.  
  872.  Specifies the location on the screen where subsequent SHOW commands will
  873.  display their strings.  The location does not have to be within the active
  874.  window set via WINROWS and WINCOLS.
  875.  
  876.  See TIMEOUT for example.
  877.  
  878.  
  879. 4.1.22 SHOWIN attr
  880.  
  881.  SHOWIN is designed as an aid to script writing.  Sometimes you will want to
  882.  restrict the active window to certain rows and columns, thus creating a
  883.  smaller active window for processing commands that read the screen.
  884.  
  885.  To make sure you have calculated the correct area for the active window, you
  886.  can use SHOWWIN to show you where the active window is located on the 
  887.  screen.  SHOWIN will change the attribute of all characters and spaces
  888.  within the active window to that specified.  See the SHOW command for
  889.  attribute values.
  890.  
  891.  HIDEWIN can then be used to restore the window to its normal attributes.
  892.  There must never be any screen reading commands (WAITFOR, WAITSCR, SEARCH,
  893.  READ and LOCATE) executed between the SHOWIN and its associated HIDEWIN.
  894.  
  895.  
  896.  Example:
  897.    
  898.     WINCOLS 10 30
  899.     WINROWS 12 22
  900.     SHOWIN
  901.     PAUSE
  902.     HIDEWIN
  903.  
  904.  
  905. 4.1.23 TICK n
  906.  
  907.  Pauses execution of subsequent script commands until the specified number
  908.  of system clock ticks (18.2 per second) have elapsed.
  909.  
  910.  Example: TICK 12
  911.  
  912.  
  913. 4.1.24 TIME hhmmss
  914.  
  915.  Pauses execution of subsequent script commands until the specified time of
  916.  day.  The time must be specified in 24-hour format.  If the time has
  917.  already passed when the TIME command is processed, processing is suspended
  918.  until the next time the specified time of day occurs.
  919.  
  920.  Leading zeros are required if the hour, minute or second is less that two 
  921.  digits.  For instance two minutes after one in the morning is entered as 
  922.  010200.
  923.  
  924.  Note- The real time clock (set by the DOS TIME command in AT and later 
  925.  machines using DOS 3.x or later) and the system timer (which EXC uses) are 
  926.  not always in synch to the second.  There may be a few seconds variation.
  927.  
  928.  Example: 
  929.  
  930.   ; At 1:15 PM, set off an alarm that can be shut off with LEFT SHIFT-RIGHT
  931.   ; SHIFT
  932.  
  933.     TIME 131500
  934.  
  935.   :Loop
  936.     BEEP
  937.     GOTO Loop
  938.  
  939.  
  940. 4.1.25 TIMEOUT label
  941.  
  942.  When the timeout limit specified by SETWAIT expires while waiting for a
  943.  WAITSCR, WAITFOR or LOCATE, TIMEOUT processing is invoked.  Timeout 
  944.  processing is as follows:
  945.  
  946.  If no TIMEOUT command has yet been issued in the script, processing of the 
  947.  script is halted at this point.  Otherwise, the control will pass to the 
  948.  command following the label specified in the last TIMEOUT command 
  949.  encountered.
  950.  
  951.  Example:
  952.  
  953.    SETWAIT 20
  954.    TIMEOUT TimedOut
  955.    SHOWAT 17 25
  956.    WINCOLS 20 40
  957.    WINROWS 15 22
  958.    CASE ON
  959.    
  960.    WAITFOR "XYZ"
  961.    SH0W 79 "Found XYZ in window."
  962.    QUIT
  963.  
  964. :TimedOut
  965.    SH0W 79 "Timed out waiting for XYZ to appear in window."
  966.    WINMAX
  967.    CASE OFF
  968.    .
  969.    .
  970.    .
  971.  
  972.  
  973. 4.1.26 TYPE "string"
  974.  
  975.  The string following the TYPE command contains ASCII characters to be placed
  976.  in the keyboard buffer.  ASCII character are those with a decimal equivalent
  977.  of 0-127.  Do not use high-bit characters (graphics characters, foreign
  978.  language characters and most symbols) that range from 128-255 in their
  979.  decimal equivalents.  These characters hove no valid keycode associated
  980.  with them.  To enter special keys such as function keys, ENTER, ESC, etc.,
  981.  use the KEY command followed by the required mnemonic.  You cannot enter
  982.  these mnemonics with the TYPE command.  The string must be enclosed in
  983.  quotes.
  984.  
  985.  See ON for example.
  986.  
  987.  
  988. 4.1.27 TYPFILE filespec [mnemonic]
  989.  
  990.  TYPFILE allows you to type the contents of a file into the keyboard buffer.
  991.  The filespec is the filename with optional path information.  
  992.  
  993.  A possible use for this would be to feed an electronic mail message to a 
  994.  communications program.  Each line of the file is entered as is (no 
  995.  deletion of leading or trailing spaces, conversion of quotes, etc.).  
  996.  
  997.  If no mnemonic is specified, the carriage return/line feed characters at 
  998.  the end of each line are ignored by EXC, and nothing is entered in their 
  999.  place.  If a mnemonic is specified, carriage return/line feed pairs are 
  1000.  converted to the key mnemonic specified.  For instance, if the file is
  1001.  being copied into a word processor or editor that uses the ENTER key to
  1002.  move to the next line, you may want to convert CR/LFs to <ENTER>.  If you
  1003.  want the word processor to split the lines according to its margins, you
  1004.  would not specify a mnemonic or you would specify <SPACE>.
  1005.  
  1006.  Specifying <SPACE> for the mnemonic will keep the last word on a line from 
  1007.  running into the first word on the next line when the CR/LF is removed.
  1008.  
  1009.  All other key mnemonics are described under the KEY command.
  1010.  
  1011.  Since EXC only has a 256 byte extended keyboard buffer, it feeds a maximum 
  1012.  of 80 bytes every clock tick into the extended buffer.  This should give 
  1013.  time for the spawned program to read characters from the buffer and will 
  1014.  usually prevent the buffer from overflowing.
  1015.  
  1016.  Please see the notes in section 3 regarding memory usage to determine the
  1017.  effects on memory of using TYPFILE.
  1018.  
  1019.  
  1020. 4.1.28 WAITFOR [NOT] "string"
  1021.  
  1022.  No further script file command will be processed until "string" appears on
  1023.  the screen.  The entire screen will be searched for "string".  The string 
  1024.  may be any valid screen characters.  If the string does not appear before 
  1025.  the SETWAIT limit expires, TIMEOUT processing will be invoked. 
  1026.  
  1027.  If NOT is specified, processing will be halted until "string" is not on the
  1028.  screen.  This is handy for waiting on a "Please wait.." type message to
  1029.  disappear.
  1030.  
  1031.  Since WAITFOR reads the screen each 1/2 second, values that flash on the
  1032.  screen for less than 1/2 second may not be detected.
  1033.  
  1034.  See TIMEOUT for example.
  1035.  
  1036.  WAITFOR NOT example:
  1037.  
  1038.    WAITFOR NOT "XYZ"
  1039.  
  1040.  
  1041. 4.1.29 WAITSCR
  1042.  
  1043.  Wait until there is any change to the screen before executing the next
  1044.  script command.  If there is no screen change before the SETWAIT limit
  1045.  expires, TIMEOUT processing will be invoked.
  1046.  
  1047.  
  1048. 4.1.30 WINCOLS start end
  1049.  
  1050.  Sometimes you may want to restrict your screen searches to a certain area
  1051.  of the screen.  WINCOLS allows you to specify what columns (far left = 1)
  1052.  you want read by all commands that read the screen (READ, SEARCH, WAITFOR,
  1053.  WAITSCR and LOCATE).  Specify the starting and ending columns inclusively.
  1054.  
  1055.  By combining WINCOLS with WINROWS, you can restrict reads to a selected
  1056.  box within the screen.  This is referred to as the active window.  Use 
  1057.  WINMAX to return the active window to the full screen.
  1058.  
  1059.  See TIMEOUT and SHOWIN for examples.
  1060.  
  1061.  
  1062. 4.1.31 WINMAX
  1063.  
  1064.  If you have restricted the active window with WINCOLS and/or WINROWS, you
  1065.  can return the active window to the full screen area by issuing a WINMAX
  1066.  command.  The size of the new active window will be determined by the 
  1067.  currently displayed columns and rows, but never exceeding the values
  1068.  specified in SCRMAX.
  1069.  
  1070.  See TIMEOUT for example.
  1071.  
  1072.  
  1073. 4.1.32 WINROWS start end
  1074.  
  1075.  Sometimes you may want to restrict your screen searches to a certain area
  1076.  of the screen.  WINROWS allows you to specify what rows (top = 1) you want 
  1077.  read by all commands that read the screen (READ, SEARCH, WAITFOR, WAITSCR 
  1078.  and LOCATE).  Specify the starting and ending rows inclusively.
  1079.  
  1080.  By combining WINCOLS with WINROWS, you can restrict reads to a selected
  1081.  box within the screen.  This is referred to as the active window.  Use 
  1082.  WINMAX to return the active window to the full screen.
  1083.  
  1084.  See TIMEOUT and SHOWIN for examples.
  1085.  
  1086.  
  1087. 4.2 Labels
  1088.  
  1089.  Labels can be up to 15 characters long and may contain letters, numbers,
  1090.  special characters or spaces.  They are treated as upper case regardless of
  1091.  how they are coded.  Duplicate labels are not allowed in the same script.
  1092.  END, end and End would all be considered duplicate labels.  If duplicate
  1093.  labels exist, all branches to the duplicate labels will go to the first
  1094.  one in the script.
  1095.  
  1096.  Labels must be immediately preceded by a colon (:) and placed on a line 
  1097.  which does not contain any commands.  
  1098.  
  1099.  labels are used as destinations for branching commands (TIMEOUT, GOTO, ON,
  1100.  IFY and IFN).
  1101.  
  1102.  It doesn't hurt a thing if you want to use labels for comments, but the 
  1103.  semicolon (;) remark is a better approach since there is no length 
  1104.  limitation on remarks and they will not be confused with labels that are 
  1105.  actual destinations.
  1106.  
  1107.  See TIMEOUT and ON for examples.
  1108.  
  1109.  
  1110. 4.3 Remarks
  1111.  
  1112.  Anything on a line for which the first non-blank character is a semicolon 
  1113.  (;) is treated as a comment line and is ignored by the script processor.
  1114.  
  1115.  
  1116. 4.4 Environment variable substituion
  1117.  
  1118.  You may use envionment strings in any command parameter by typing %VAR%
  1119.  where you want the environmentstring labeled VAR to be substituted.  Here
  1120.  are some examples:
  1121.  
  1122.  Given these environment varables:
  1123.   SET ATTR=15
  1124.   SET ME=Gary
  1125.   SET LAST=Crider
  1126.   SET FULL="Gary Crider"
  1127.   SET FULL2=Gary Crider
  1128.  
  1129.   SHOW %ATTR% "I am %ME%"  would equate to  SHOW 15 "I am Gary"
  1130.   TYPE "%ME% %LAST%"       would equate to  TYPE "Gary Crider" 
  1131.   TYPE %FULL%              would equate to  TYPE "Gary Crider"
  1132.   TYPE "%FULL2%"           would equate to  TYPE "Gary Crider"
  1133.   DELAY %ATTR%             would equate to  DELAY 15
  1134.   SHOW %ATTR% "%FULL%"     would equate to  SHOW 15 "\qGary Crider\q"
  1135.   TYPE "%LAST%, %ME%"      would equate to  TYPE "Crider, Gary"
  1136.  
  1137.  The substitution is made before EXC begins to evaluate the parameters.
  1138.  
  1139.  This could be handy on networks where the values keyed or searched might 
  1140.  vary with the user's network ID, which could be stored in an environment
  1141.  variable.  Many other uses also come to mind.
  1142.  
  1143.  
  1144. 4.5 Example Script
  1145.  
  1146.  The following example demonstrates the use of most of the more commonly used 
  1147.  commands.  Please note that the  QUIT statement after the End label is not 
  1148.  needed since the same action takes place when there are no more commands to 
  1149.  execute.
  1150.  
  1151.  Also please note that the SEARCH and IFN statements after the Loop label
  1152.  could more easily be accomplished with a WAITFOR command.  This just 
  1153.  demonstrates that looping logic is supported in scripts.
  1154.  
  1155.    SETWAIT 30
  1156.    TIMEOUT End
  1157.    CASE OFF
  1158.    WAITFOR "Entries"
  1159.    CASE ON
  1160.    TYPE "FO"
  1161.    WAITFOR "OPEN CATALOG"
  1162.    TYPE "E:\NOVLIB\"
  1163.    KEY <TAB>
  1164.    KEY <ESC>
  1165.    TYPE "NOVLIB.L11"
  1166.    KEY <CTL+ENTER>
  1167.    WAITSCR
  1168.  
  1169.  :Loop
  1170.    SEARCH "NOVLIB.L11"
  1171.    IFN Loop
  1172.  
  1173.    TYPE "SLADDNAEA"
  1174.    KEY <CTL+ENTER>
  1175.    DELAY 2;
  1176.    WAITFOR NOT "Sorting Index"
  1177.    TYPE "FS"
  1178.    KEY <CTL+ENTER>
  1179.    DELAY 2
  1180.    WAITFOR NOT "Please wait."
  1181.  
  1182.  :End   
  1183.    BEEP
  1184.    KEY <ALT+X>
  1185.    QUIT
  1186.  
  1187.  
  1188.  For a more comprehensive example, see the script file, TESTEXC.SCR.  Please
  1189.  read the comments before and after that script.
  1190.  
  1191.  
  1192.  
  1193. APPENDIX A
  1194.  
  1195. Installation
  1196.  
  1197.     EXC is distributed in a ZIP file called EXC.ZIP.  It contains the
  1198. following files:
  1199.  
  1200.         EXC.EXE         The executable file for EXC.
  1201.         EXC.DOC         The documentation file.
  1202.         HELP.TXT        Script command quick reference.  It is formatted as
  1203.                         script file comments so that it can be included in
  1204.                         you script for quick referencing.z
  1205.         TESTEXC.SCR     Example script used to test EXC functionality.
  1206.         TESTEXC.TXT     Text file for testing TYPFILE with TESTEXC.SCR.
  1207.         EXC.Vnn         Text description of updates in version nn.
  1208.         PRODUCTS.DOC    Description of other Parity Solutions products.
  1209.  
  1210.     For best results, unzip the file into a directory on your PATH.  If you
  1211. don't use a directory in your path, you will have to designate the directory
  1212. containing EXC.EXE when executing the program.
  1213.  
  1214.     If you have a utility directory that is on your PATH, this is an excellent
  1215. location for EXC.  An example installation would be:
  1216.  
  1217.     C:
  1218.     CD \UNTIL
  1219.     COPY [path]EXC.ZIP
  1220.     PKUNZIP EXC
  1221.     DEL EXC.ZIP
  1222.  
  1223.     The PKUNZIP program is by PKWARE, Inc. and is available in many CompuServe
  1224. forums under the file name of PKZ110.EXE.  Since you are reading this doc
  1225. files, you have obviously already managed to unZIP the distribution file.  If 
  1226. it is not currently in your path, simply copy all of the files to a directory 
  1227. in your path.  Keep the EXC.ZIP file anywhere you like, but give plenty of
  1228. copies, as is, to your friends.  If you register EXC, you are not licensed
  1229. to give your serial number to anybody without first removing the serialization
  1230. from your copy.
  1231.  
  1232.  
  1233.  
  1234.  
  1235. APPENDIX B
  1236.  
  1237.  
  1238. Keycode Table
  1239.  
  1240. Although you do not need to know these codes to write EXC scripts, the
  1241. following table does show you which combinations are defined and available
  1242. by using the appropriate mnemonics.  Do not try to use combinations which
  1243. indicate N/A in the table.
  1244.  
  1245.  Key             Norm        Shift       Ctrl        Alt
  1246.  ----            ----        -----       ----        ---
  1247.  A               1E61        1E41        1E01        1E00
  1248.  B               3062        3042        3002        3000
  1249.  C               2E63        2E42        2E03        2E00
  1250.  D               2064        2044        2004        2000
  1251.  E               1265        1245        1205        1200
  1252.  F               2166        2146        2106        2100
  1253.  G               2267        2247        2207        2200
  1254.  H               2368        2348        2308        2300
  1255.  I               1769        1749        1709        1700
  1256.  J               246A        244A        240A        2400
  1257.  K               256B        254B        250B        2500
  1258.  L               266C        264C        260C        2600
  1259.  M               326D        324D        320D        3200
  1260.  N               316E        314E        310E        3100
  1261.  O               186F        184F        180F        1800
  1262.  P               1970        1950        1910        1900
  1263.  Q               1071        1051        1011        1000
  1264.  R               1372        1352        1312        1300
  1265.  S               1F73        1F53        1F13        1F00
  1266.  T               1474        1454        1414        1400
  1267.  U               1675        1655        1615        1600
  1268.  V               2F76        2F56        2F16        2F00
  1269.  W               1177        1157        1117        1100
  1270.  X               2D78        2D58        2D18        2D00
  1271.  Y               1579        1559        1519        1500
  1272.  Z               2C7A        2C5A        2C1A        2C00
  1273.  1               0231        0221        N/A         7800
  1274.  2               0332        0340        0300        7900
  1275.  3               0433        0423        N/A         7A00
  1276.  4               0534        0524        N/A         7B00
  1277.  5               0635        0625        N/A         7C00
  1278.  6               0736        075E        071E        7D00
  1279.  7               0837        0826        N/A         7E00
  1280.  8               0938        092A        N/A         7F00
  1281.  9               0A39        0A28        N/A         8000
  1282.  0               0B30        0B29        N/A         8100
  1283.  ,               332C        333C        N/A         N/A
  1284.  .               342E        343E        N/A         N/A
  1285.  /               352F        353F        N/A         N/A
  1286.  ;               273B        273A        N/A         N/A
  1287.  '               2827        2822        N/A         N/A
  1288.  [               1A5B        1A7B        1A1B        N/A
  1289.  ]               1B5D        1B7D        1B1D        N/A
  1290.  `               2960        297E        N/A         N/A
  1291.  -               0C2D        0C5F        0C1F        8200
  1292.  =               0D3D        0D2B        N/A         8300
  1293.  \               2B5C        2B7C        2B1C        N/A
  1294.  F1              3B00        5400        5E00        6800
  1295.  F2              3C00        5500        5F00        6900
  1296.  F3              3D00        5600        6000        6A00
  1297.  F4              3E00        5700        6100        6B00
  1298.  F5              3F00        5800        6200        6C00
  1299.  F6              4000        5900        6300        6D00
  1300.  F7              4100        5A00        6400        6E00
  1301.  F8              4200        5B00        6500        6F00
  1302.  F9              4300        5C00        6600        7000
  1303.  F10             4400        5D00        6700        7100
  1304.  Enter           1C0D        1C0D        1C0A        N/A
  1305.  Ins             5200        5230        N/A         N/A
  1306.  Del             5300        532E        N/A         N/A
  1307.  Esc             011B        011B        011B        N/A
  1308.  Home            4700        4737        7700        N/A
  1309.  End             4F00        4F31        7500        N/A
  1310.  PgUp            4900        4939        8400        N/A
  1311.  PgDn            5100        5133        7600        N/A
  1312.  <Tab>           0F09        0F00        N/A         N/A
  1313.  <BackSpace>     0E08        0E08        0E7F        N/A
  1314.  <LeftArrow>     4B00        4B34        7300        N/A
  1315.  <RightArrow>    4D00        4D36        7400        N/A
  1316.  <UpArrow>       4800        4838        N/A         N/A
  1317.  <DownArrow>     5000        5032        N/A         N/A
  1318.  <Gray 5>        N/A         4C35        N/A         N/A
  1319.  <Gray *>        372A        N/A         7200        N/A
  1320.  <Gray ->        4A2D        4A2D        N/A         N/A
  1321.  <Gray +>        4E2B        4E2B        N/A         N/A
  1322.  <Space>         3920        N/A         N/A         N/A
  1323.  <F11>           8500        8700        8900        8B00
  1324.  <F12>           8600        8800        8A00        8C00
  1325.  
  1326.  In addition, the <PRTSC> (print screen) mnemonic can be used in EXC to
  1327. cause a screen print.  The <PRTSC> cannot be placed in the keyboard buffer
  1328. since it does not have a key code.  KEY <PRTSC> is executed immediately.
  1329.  
  1330.  
  1331.  
  1332.  
  1333. APPENDIX C
  1334.  
  1335.  
  1336. Disclaimer
  1337.  
  1338. BECAUSE OF THE DIVERSE NATURE OF COMPUTER EQUIPMENT AND EXPERTISE OF USERS,
  1339. PARITY SOLUTIONS AND GARY C. CRIDER MAKE NO WARRANTY ON THE EXC PROGRAM
  1340. WHATSOEVER, EXPRESS OR IMPLIED.  THE USER ASSUMES ALL RISK OF DAMAGE TO
  1341. DATA OR EQUIPMENT RESULTING DIRECTLY OR INDIRECTLY FROM THE USE OR MISUSE OF
  1342. THIS PROGRAM PRODUCT.
  1343.  
  1344. USERS ARE ADVISED TO TEST PROGRAMS AND SCRIPTS THOROUGHLY ON DATA FOR WHICH A
  1345. BACKUP EXITS.  ANY LIABILITY OF THE AUTHOR OR PARITY SOLUTIONS IS LIMITED TO
  1346. REPLACEMENT OR REFUND OF THE REGISTRATION FEE.
  1347.  
  1348.  
  1349.  
  1350.  
  1351. APPENDIX D
  1352.  
  1353.  
  1354. Support
  1355.  
  1356.     I have tried to test the program to the fullest, but I am limited as to
  1357. systems and configurations with which to test.  I have been programming for 18
  1358. years and the one thing I know for sure is that bug free programs are very few
  1359. and far between.  I can only promise to support the program to the best of my
  1360. ability and provide fixes as expeditiously as possible.
  1361.  
  1362.     Anyone can report problems and suggest changes.  Registered users get top
  1363. priority in resolving their problems.  There are three ways you can report
  1364. problems.  The preferred method is to contact me through CIS mail (not forum
  1365. messages).  My CIS ID is 71760,3413.  You can also write me at:
  1366.  
  1367.    Gary C. Crider
  1368.    Parity Solutions
  1369.    1105 Burgess Court
  1370.    Arlington, TX 76015
  1371.  
  1372.     The last method is to phone (817) 467-7818.  Since I am the sole technical
  1373. support and the line is also used for my network consulting business, it is
  1374. often hard to get through to me.  Please call and leave a message between 7:30
  1375. am and 5:30 pm Central time.
  1376.  
  1377.     No matter which method you use, please give a brief description of your
  1378. problem, your registration serial number if you are registered, and your phone
  1379. number.  If I need more information, I will contact you as soon as I can.
  1380. When I have a solution, I will contact you however you prefer.  Never post
  1381. your serial number on forum messages.  CIS mail is OK.  I seldom read forum
  1382. messages and they are not private.
  1383.  
  1384.     I work full time, have a consulting business to run in my spare time and
  1385. write programs instead of sleeping.  So please be a little patient with me.
  1386.  
  1387.     To keep prices this low, new releases are posted on CompuServe in the 
  1388. NOVLIB, IBMSYS and ZENITH forums, and on ZiffNet in the PBS forum.
  1389.  
  1390.                  
  1391. APPENDIX E
  1392.  
  1393.  
  1394. Registration
  1395.  
  1396.  
  1397.     I begin with an apology.  I hate programs that in any way inhibit func-
  1398. tionality or performance for the shareware version.  But when it came down to
  1399. feeding the family and paying the bills, I had a change of heart and inserted
  1400. a pesky notice that pops up at the beginning and gets on your nerves.  I
  1401. chose this approach above that of limited functionality.  The program's full
  1402. capabilities are available for you to evaluate before you invest your hard-
  1403. earned money.
  1404.  
  1405.     Registered users will receive a unique serial number and instructions on
  1406. how to serialize the program.  Serialization can be re-applied to updated
  1407. versions and in no way hinders your use of the program.  You can compress or
  1408. decompress the program with no effect (LZEXE or PKLITE).  I use Fabrice
  1409. Bellard's LZEXE program on EXC.EXE before distribution.
  1410.  
  1411.     As a registered user, you will be able to update without re-registration
  1412. or additional fees.  You will also be kept on my PRIVATE mailing list to
  1413. receive additional information on other Parity Solutions products.  Registered 
  1414. users will be entitled to a discount on any present or future Parity Solutions
  1415. software.
  1416.  
  1417.     To register your copy, please send $20 US ($80 per file server on LANS) 
  1418. check or money order (sorry, no credit cards yet) to:
  1419.  
  1420.    Gary C. Crider
  1421.    Parity Solutions
  1422.    1105 Burgess Court
  1423.    Arlington, TX 76015
  1424.  
  1425.     Or, you can register online quickly and simply in Compuserve.  Simply
  1426. GO SWREG and register ID #753.  Your registration will be added to your 
  1427. Compuserve bill.  International exchange was never easier. 
  1428.  
  1429.     If you send your CIS id or register via CIS:SWREG, your registration will 
  1430. be sent to you via CIS mail, along with instructions on how to serialize your 
  1431. copy of EXC.  This usually involves one day or less turnaround.
  1432.     
  1433.     Each license gives you or your company a single use permit for EXC.  It is 
  1434. not restricted to a single machine as long as no two users can be simul-
  1435. taneously using the program.  As Borland says, "treat it like a book."  As an 
  1436. example, if you register EXC for your home computer, but during the day you 
  1437. use a portable or a computer at work,  you may keep EXC on both machines as 
  1438. long as no one is at home using it on your home computer.
  1439.  
  1440.     LAN licenses grant rights to all workstations on the same physical LAN.  If 
  1441. internetworking, a license must exist for each file server that contains a 
  1442. copy of EXC.EXE.  If two or more file servers exist on a single LAN strictly 
  1443. for mirroring data and fault-tolerance, these will be counted as a single 
  1444. file server for licensing purposes.  If in doubt, contact me.  We can work 
  1445. out an agreement.
  1446.  
  1447.     Site licensing is also available on a negotiated price basis.  I guarantee
  1448. it will be an economical alternative to buying licenses for each user.
  1449.  
  1450.     You may freely distribute the original EXC.ZIP file in any way you see
  1451. fit other than selling it.  Users' groups and shareware distribution services
  1452. may charge a reasonable fee for the medium and duplication costs.  Bulletin 
  1453. boards may not charge additional fees for downloading this specific program, 
  1454. other than normal connect-time and/or membership charges.
  1455.  
  1456.     You are NOT licensed to give anyone your serial number unless you first
  1457. remove all serialization from your computer.  You may then no longer use that
  1458. serial number.  Only Parity Solutions has the authority to issue serial
  1459. numbers.
  1460.